Payment Settlement Detail

Payment settlement detail explains how individual payments connect to settlement activity, including which batch they belong to, which settlement covers them, and their current settlement status.

Use this when you need to trace a specific payment through the settlement lifecycle, build payment-level reconciliation reports, or investigate whether and how a payment has settled.

For period-level fee totals and net fundable amounts, use Settlements. For batch-level groupings and fee rollups, use Batches. For funded bank movement, use Deposits.

When to use Payment Settlement Detail

Use payment settlement detail when you need to:

• Connect a completed payment to its settlement and batch.

• Check whether a payment has been batched.

• Review batch period and batch status for a payment.

• Build reconciliation reports that combine payment and settlement data.

• Investigate a payment's settlement status.

• Identify the payments behind a specific settlement.

How it works

Every PaymentResponse includes four settlement fields that show where a payment sits in the settlement lifecycle: settlementId, batchId, batchPeriod, and batchStatus. These fields populate as the payment moves through the batch and settlement workflow. Payments that have not yet been batched return null for all four fields.

To navigate from a settlement down to its payments, use the batch path: retrieve batches for the settlement using GET /Settlements/{id}/batches, then use the paymentIds array on each batch to identify the underlying payments.

To navigate in the other direction, starting from a payment, fetch the payment from GET /Merchants/{merchantId}/payments and read the settlement fields directly from the response.

A typical payment settlement review flow:

1. Retrieve settlement records for a merchant using GET /Merchants/{merchantId}/settlements.

2. Select the settlement to review.

3. Retrieve batches for that settlement using GET /Settlements/{id}/batches.

4. Use paymentIds on each batch to identify the payments included.

5. Review settlementId, batchId, batchPeriod, and batchStatus on each payment to confirm settlement context.

Settlement fields on PaymentResponse

Every payment returned from GET /Merchants/{merchantId}/payments includes the following settlement fields:

Field	Type	Description
settlementId	string or null	Settlement covering this payment. Null until the payment is included in a settlement.
batchId	string or null	Batch this payment belongs to. Null until the payment is batched.
batchPeriod	date or null	Date associated with the batch period.
batchStatus	string or null	Current status of the batch. See Batch status.

A payment progresses through this state sequence:

• batchId null, settlementId null: payment is completed but not yet batched.

• batchId set, settlementId null: payment is in a batch not yet tied to a settlement.

• batchId set, settlementId set: payment is part of a closed settlement.

Available endpoints

Scope	Path	Description
Merchant settlement list	GET /Merchants/{merchantId}/settlements	Returns settlement records for a specific merchant.
Batches for a settlement	GET /Settlements/{id}/batches	Returns batch records for a settlement. Each batch includes paymentIds.
Merchant payment list	GET /Merchants/{merchantId}/payments	Returns payments for a merchant. Each payment includes settlement fields.

Query parameters

GET /Merchants/{merchantId}/settlements

Parameter	Type	Description
From	date	Start of the date range filter.
To	date	End of the date range filter.
Status	string	Filter by settlement state. See Settlement state.
Type	string	Filter by currency category: crypto, walletApps, or fiat.
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.

Date format: From and To accept date-only values (2026-06-22). ISO date-times with a .000Z suffix fail validation.

GET /Merchants/{merchantId}/payments

Parameter	Type	Description
From	date-time	Start of the date range filter.
To	date-time	End of the date range filter.
StatusCode	array of strings	Filter by payment status.
TenderType	array of strings	Filter by tender type.
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.

Filtering by settlement: GET /Merchants/{merchantId}/payments does not support filtering by settlementId or batchId. To retrieve the payments belonging to a specific settlement, use GET /Settlements/{id}/batches and read paymentIds from each batch record.

Typical integration flows

Trace a settlement to its payments

Goal: identify the payments that make up a settlement.

1. Retrieve the settlement using GET /Settlements/{id} or GET /Merchants/{merchantId}/settlements.

2. Retrieve batches for the settlement using GET /Settlements/{id}/batches.

3. Review each batch for paymentIds, batchPeriod, status, and fee totals.

4. Use the paymentIds list to retrieve or cross-reference individual payments.

Check settlement status for a payment

Goal: determine whether a specific payment has been settled.

1. Retrieve the payment using GET /Merchants/{merchantId}/payments.

2. Check batchId on the PaymentResponse.

3. If batchId is null, the payment has not yet been batched. Confirm statusCode is completed as only completed payments are eligible for settlement.

4. If batchId is set but settlementId is null, the payment is in a batch not yet tied to a settlement.

5. If settlementId is set, retrieve the settlement using GET /Settlements/{id} to review status, fees, and net fundable amount.

Build a payment-level reconciliation report

Goal: combine payment and settlement data for a reporting window.

1. Retrieve settlements for the merchant and date range using GET /Merchants/{merchantId}/settlements.

2. For each settlement, retrieve batches using GET /Settlements/{id}/batches.

3. Use paymentIds from each batch to retrieve the underlying payments.

4. Group by settlementId and batchId for reconciliation context.

5. Match payment amounts to batch fee totals and the settlement's netFundableAmount.

Investigate an unsettled payment

Goal: determine why a completed payment has not appeared in a settlement.

1. Retrieve the payment and review batchId.

2. If batchId is null, the payment has not been batched. Confirm statusCode is completed as only completed payments are eligible.

3. If batchId is set, retrieve the batch using GET /Settlements/{id}/batches and check batch status.

4. A batch with status hold is pending review. Contact Bead support if the hold is unexpected.

Next steps

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

• Use Batches to review grouped payment activity and verify fee rollups.

• Use Deposits to confirm funded bank movement tied to a settlement.

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