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.

Building a report for a Split Funding Program partner? The settlement-level fields on this page cover standard processing residuals. They are not the source of truth for a split funding partner distribution. See Split Funding Program merchants below.

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, and others), along with netAdjustmentTotal, the signed sum of those adjustments.

5. Bead funds the merchant the netFundableAmount, which is gross minus all fees plus the signed adjustment total.

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
Rolled-up fee total	SettlementResponse	totalFees	The settlement's own single fee total for the period
Adjustments	SettlementResponse	adjustments[]	Chargebacks, refunds, platform fees, holdbacks, and others
Adjustments (signed total)	SettlementResponse	netAdjustmentTotal	Signed sum of netAdjustment across adjustments[]
Batch count for the period	SettlementResponse	batchCount	Number of batches rolled into the settlement
Net payout to merchant	SettlementResponse	netFundableAmount	What the merchant received after all deductions
Partner portion (informational)	Settlement report row (SettlementReportRow)	partnerPortion	Sum of the partner portion across the settlement's split funding payments; not part of the payable math. Not the distribution source of truth. See below. This field is not on SettlementResponse; read it from the settlement report.
Split funding payment count	Settlement report row (SettlementReportRow)	splitFundingTransactionCount	Number of split funding payments in the settlement. Not on SettlementResponse; read it from the settlement report.

Transaction fees are not tracked at the individual payment level for standard processing. 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.

From and To bound the settlement created-date window in UTC. They filter on the settlement's created date, not on settlementDate, and they are date-only values (2026-06-01). A full ISO timestamp with a time component fails validation. If your report needs to be organized by actual settlement date, retrieve by created-date window and then group on settlementDate yourself.

Step 2: Retrieve settlements for the period

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

Retrieve one page at a time. Page is zero-based and defaults to 0. PageSize defaults to 50 and accepts up to 100. 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

• totalFees

• adjustments, iterating the array and noting type and amount for each

• netAdjustmentTotal

• netFundableAmount

• settlementDate (nullable; populated once the settlement has an actual settlement date)

• status, filtered to dispatched or paid to include only funded settlements

There is no targetPayoutDate field on SettlementResponse. The only date fields on the record are settlementDate, created, and updated. Use settlementDate for the actual settlement date and created for the window the From and To filters act on.

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,369.75
S-002	$18,000	$432	$0.25	none	$17,567.75
S-003	$12,000	$288	$0.25	+$50 (credit)	$11,761.75

Each row is gross minus transaction fees minus the deposit fee plus the signed adjustment total:

• S-001: 20,000 - 480 - 0.25 - 150 = 19,369.75

• S-002: 18,000 - 432 - 0.25 = 17,567.75

• S-003: 12,000 - 288 - 0.25 + 50 = 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: $48,699.25

The period total reconciles both ways: 50,000 - 1,200 - 0.75 - 100 = 48,699.25, and 19,369.75 + 17,567.75 + 11,761.75 = 48,699.25.

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. Page is zero-based and defaults to 0, and PageSize defaults to 50, so a request that does not set PageSize returns 50 records per page rather than 100. 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. When a settlement is in hold, read holdReason for the reason it is held.

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.

Split Funding Program merchants

A merchant enrolled in the Split Funding Program settles split funding payments at merchantPortion with no transaction fee, and the withheld difference is paid to the partner separately, on its own cadence, net of Bead's fee. This is a fundamentally different revenue flow from standard residual reporting, and the two should not be blended in the same calculation.

Split funding payments do not generate residuals. Residual reporting derives partner revenue from fees Bead withheld from the merchant. On the Split Funding Program the merchant is charged nothing, so there is no fee to derive a residual from, and the partner's margin has already been paid to them through the distribution. A partner cannot be paid a residual and a split funding distribution on the same payment. If a partner moves traffic onto the program, residual revenue on that traffic stops and is replaced by the distribution. Build residual reports from non-split-funding payments only.

Expect the distribution to differ from the residual it replaces. A residual derives from fees Bead charged the merchant. A split funding distribution is the consumer fee the partner collected, less Bead's fee on the merchant portion and the settlement fees. They are calculated from entirely different things and will not be the same size. Do not model a distribution as equal to the residual the same traffic would have produced. See Bead's split funding fee.

The partner portion total and the split funding payment count on the settlement report are informational aggregates. They tell you split funding activity happened, not what the partner is owed. They are computed at the settlement report level, but the actual partner distribution is assessed from payments directly. This matters once refunds apply: no Bead tender currently supports a refund, but the distribution logic is already built so that a refunded or partially refunded payment would be excluded from the payout at the payment level, not the settlement level, whenever that becomes possible.

Do not use the settlement-level partner portion as a partner residual figure. Use Split Funding Reports instead:

• The split funding transaction report gives per-payment detail.

• The distribution summary gives the authoritative per-merchant, per-MID reconciliation, including Bead's fee and partner net. This is what was actually paid.

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 Payment Settlement Detail for the merchant-level settlement event view.

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

• Use Split Funding Reports for Split Funding Program partner distributions. Do not use this page's settlement totals for that purpose.

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