For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Last updated