Batches

Batches group completed payments for settlement processing and reconciliation.

Use Batches when you need to see which payments were grouped together, review batch-level fee totals, or connect grouped payment activity to a settlement record.

For payment history and transaction-level search, use Reporting first. For the settlement-level fee rollup, use Settlements. For payment-level settlement detail, use Payment Settlement Detail. For funded bank movement, use Deposits.

When to use Batches

Use Batches when you need to:

• Review which payments were grouped into a batch.

• See batch-level gross amount, fees, and net fundable amount.

• Validate that batch fee totals roll up to the settlement's totalTransactionFees.

• Filter batch activity by merchant, settlement, date range, status, or type.

• Connect batch activity to a settlement record.

• Reconcile a settlement back to the individual payments behind it.

How it works

When payments complete, Bead groups them into a batch for the settlement period. Each batch carries a grossFundableAmount, a totalFees amount representing the transaction fees withheld, and a netFundableAmount. When the settlement period closes, batches are rolled into a Settlements record. The sum of totalFees across all batches equals the totalTransactionFees on the Settlement.

A typical batch reconciliation flow:

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

2. Retrieve batch records using the relevant filters.

3. Review gross fundable amount, total fees, net fundable amount, and transaction count.

4. Use paymentIds to connect the batch back to individual payments.

5. Use settlementId to connect the batch to the parent settlement record.

Available endpoints

Scope	Path	Description
Batch list	GET /Batches	Returns batch records with filters for date range, status, type, merchant, settlement, pagination, and sorting.
Single batch	GET /Batches/{id}	Returns one batch record by batch ID.
Merchant batches	GET /Batches/merchants/{merchantId}	Returns batch records for a specific merchant.
Settlement batches	GET /Settlements/{id}/batches	Returns batch 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 batch status. See Batch status.
Type	string	Filter by currency category: crypto, walletApps, or fiat.
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.

Batch fields

Field	Type	Description
id	string	Unique batch identifier.
merchantId	string	Merchant associated with the batch.
status	string	Current batch status. See Batch status.
type	string	Batch currency category. See Batch type.
totalFees	number or string	Transaction fees withheld for this batch. Sums to totalTransactionFees on the parent Settlement.
grossFundableAmount	number or string	Total payment volume in the batch before fees.
netFundableAmount	number or string	Net amount after fees.
transactionCount	integer or string	Number of payments included in the batch.
paymentIds	array of strings	Payment IDs included in the batch.
targetRebate	number or string	Sum of targetRebate across rebate payments in the batch. Zero if none. Informational — see Settlements.
rebateTransactionCount	integer or string	Number of rebate payments in the batch. Zero if none.
batchPeriod	date	Date associated with the batch period.
settlementId	string or null	Settlement associated with the batch, when assigned.

Batch status

Value	Description
open	Batch is open and accepting payments.
closed	Batch has been closed and submitted for settlement.
hold	Batch is on hold pending review.

Batch type

Value	Description
crypto	Batch contains crypto payments.
walletApps	Batch contains wallet app payments.
fiat	Batch contains fiat card payments.

Fee rollup

Batch fees roll up to the settlement level. For any settlement, the sum of totalFees across all associated batches equals the totalTransactionFees on the Settlement record.

Use this to cross-check settlement-level fee totals against batch-level detail. If there is a discrepancy, contact Bead support.

A rebate payment contributes merchantPortion to the batch's grossFundableAmount with a transaction fee of zero — see Rebate Program.

Typical integration flows

Review batches for a merchant

Goal: show batch activity for a merchant.

1. Retrieve batches filtered by MerchantIds and date range.

2. Display batch status, type, batch period, gross fundable amount, total fees, net fundable amount, and transaction count.

3. Allow the user to select a batch for payment-level detail.

Reconcile a settlement to batches

Goal: understand which batches are included in a settlement.

1. Use GET /Settlements/{id}/batches to retrieve batches for the settlement.

2. Review each batch's gross fundable amount, totalFees, net fundable amount, and transaction count.

3. Confirm that the sum of totalFees across all batches matches totalTransactionFees on the settlement.

Reconcile a batch to payments

Goal: connect a batch back to the payments in it.

1. Retrieve the batch record.

2. Use paymentIds to retrieve the underlying payments. See Payment Settlement Detail to review settlement context for those payments.

3. Match batch totals to your internal ledger.

Next steps

• Use Settlements for the period-level fee rollup, adjustments, and net fundable amount.

• Use Residual Reporting to understand how batch fees feed into monthly residual calculations.

• Use Deposits to confirm funded bank movement tied to 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 batches.

• If the merchant is on the Rebate Program, see Rebate Program for how targetRebate and rebateTransactionCount are produced, and Rebate Reports for partner distribution reconciliation.