Batches

Batch records help integrators understand how completed payments are grouped for settlement processing and reconciliation.

Use Batches when you need to see which payments were grouped together, review batch-level amounts, or connect a group of payments to a settlement record.

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

When to use Batches

Use Batches when you need to:

• Review groups of payments prepared for settlement.

• See which payment IDs are included in a batch.

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

• Compare gross fundable amount, fees, and net fundable amount.

• Connect batch activity to settlement records.

• Reconcile a settlement back to the payments included in it.

• Support merchant or partner questions about how payments were grouped.

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

How it works

A batch groups one or more payments for settlement processing.

A typical batch reconciliation flow is:

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

2. Retrieve batch records using the relevant filters.

3. Review the batch status, type, batch period, and settlement identifier.

4. Use the payment IDs in the batch to reconcile individual payments.

5. Use the settlement identifier to connect the batch to settlement and deposit activity.

Available endpoints

Scope	Path	Description
Batch list	/Batches	Returns batch records with filters for date range, status, type, merchant, settlement, pagination, and sorting.
Single batch	/Batches/{id}	Returns one batch record by batch ID.
Merchant batches	/Batches/merchants/{merchantId}	Returns batch records for a specific merchant.
Settlement batches	/Settlements/{id}/batches	Returns batch records associated with a settlement.

Shared query parameters

The batch list, merchant batch, and settlement batch endpoints support filters that help narrow results for reconciliation and support workflows.

Common filters include:

• From

• To

• Status

• Type

• 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 merchant and date filters when reviewing activity for a known merchant and settlement period. Use settlement filters when reconciling a known settlement. Use status and type filters when reviewing settlement workflow or currency category.

Batch fields

A batch record can include:

Field	Type	Description
id	string	Unique batch identifier.
merchantId	string	Merchant associated with the batch.
status	string	Current batch status. Expected values include open, closed, and hold.
type	string	Batch currency category. Expected values include crypto, walletApps, and fiat.
totalFees	number	Total fees associated with the batch.
grossFundableAmount	number	Gross fundable amount before fees are applied.
netFundableAmount	number	Net fundable amount after fees are applied.
transactionCount	integer	Number of transactions included in the batch.
paymentIds	array of strings	Payment IDs included in the batch.
batchPeriod	date	Date associated with the batch period.
settlementId	string or null	Settlement associated with the batch, when assigned.

Batch status

Batch status indicates the current state of the batch.

Supported status values include:

• open

• closed

• hold

Use the status field to filter batch records and display batch state in reconciliation or support workflows.

Batch type

Batch type identifies the currency category for the batch.

Supported type values include:

• crypto

• walletApps

• fiat

Use the type field when separating crypto, wallet app, and fiat settlement activity.

Relationship to Settlement

Batches are part of the broader Settlement model.

Use Batches when you need to understand which payments were grouped together. Use Settlement records to understand the broader settlement event. 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 Batches to understand how those payments were grouped.

3. Use Settlement APIs to connect the batch to a settlement record.

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

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

Files, exports, and API reporting

Batch data is available through Bead APIs.

Most integrations should use the documented API responses for batch 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

Review batches for a merchant

Goal: show batch activity for one merchant.

High level steps:

1. Identify the merchant ID.

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

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

4. 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.

High level steps:

1. Start with a settlement ID.

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

3. Review each batch’s gross fundable amount, total fees, net fundable amount, transaction count, and payment IDs.

4. Compare the batch totals to the related settlement record.

Reconcile a batch to payments

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

High level steps:

1. Retrieve the batch record.

2. Use the paymentIds array to identify the payments in the batch.

3. Retrieve payment history or payment settlement detail for those payments.

4. Match batch totals, fees, and net fundable amount to your internal ledger.

Investigate a batch question

Goal: answer a merchant or partner question about how payments were grouped.

High level steps:

1. Search batches by merchant, settlement, date range, status, or type.

2. Review the batch status and batch period.

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

4. Use the payment IDs to review the underlying payments.

Next steps

• Use Settlement records when you need the broader settlement event.

• Use Merchant Settlements for merchant-level settlement batches.

• Use Payment Settlements for payment-level settlement detail.

• Use Deposits when you need funded movement and deposit status.

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