Settlement

The Settlement section helps integrators understand how completed payments are grouped, calculated, funded, and reconciled.

Use Settlement when you need to connect completed payment activity to settlement records, batch groupings, payment-level settlement detail, and deposit or funding information.

Settlement works together with Payments and Reporting:

• Payments describe individual transactions.

• Reporting APIs return payment history by partner, merchant, terminal, tender type, status, date range, and reference.

• Settlement APIs explain how completed payments were grouped, settled, and funded.

If you need payment search or transaction history, start with Reporting. If you need settlement grouping, fee breakdowns, payout timing, funding status, or reconciliation details, use Settlement.

Building residual or revenue-share reports? Start with Settlements. It is the authoritative source for transaction fees, deposit fees, adjustments, and net fundable amount per settlement period. Then see the Residual Reporting guide for the full integration pattern.

When to use Settlement

Use Settlement when you need to:

• Review gross amount, fees, adjustments, and net payout for a settlement period.

• Show merchant settlement history.

• Build daily or monthly reconciliation jobs.

• Build partner residual reporting.

• Connect settled funds back to individual payments.

• Review batch-level settlement activity.

• Identify the batch and settlement a payment belongs to, and the state of that batch.

• Confirm deposit or funding information.

• Investigate settlement-related support questions.

• Match Bead settlement activity to your internal ledger or accounting system.

How it works

Settlement starts after a payment has completed and becomes eligible for settlement.

A typical reconciliation flow is:

1. Use Reporting APIs to identify the payments you care about.

2. Use GET /Merchants/{merchantId}/settlements to retrieve settlement records for a merchant.

3. Use Settlement records to review period-level fee totals, adjustments, and net fundable amount.

4. Use GET /Settlements/{id}/batches to review batch-level groupings and connect settlements back to payments.

5. Use the settlement linkage fields on each PaymentResponse to identify the batch and settlement the payment belongs to.

6. Use Batches and Deposits when you need to reconcile funded amounts back to payments.

Core settlement concepts

Settlements

A settlement is the top-level funding record for a settlement period. It rolls up all batch activity for a merchant into a single record that captures gross fundable amount, total transaction fees, deposit fees, total fees, adjustments, net adjustment total, and net fundable amount.

Use Settlements when you need fee totals, net payout amounts, adjustment detail, or the basis for residual and revenue-share reporting. Retrieve settlement records for a specific merchant using GET /Merchants/{merchantId}/settlements.

Payments

A payment is the original transaction created through the Payments API. Payment records include transaction-level information such as amount, tender type, status, merchant, terminal, reference, and tracking identifiers.

Every PaymentResponse includes exactly four settlement linkage fields: settlementId, batchId, batchPeriod, and batchStatus. settlementId and batchId identify the settlement and batch the payment belongs to, batchPeriod is the date of the batch period, and batchStatus is the state of the batch (open, closed, or hold). These fields populate as the payment moves through batching and settlement.

batchStatus is a property of the batch, not of the individual payment. There is no payment-level settlement status field and no timestamp recording when a payment was included in a settlement. To reason about settlement state, read the settlement record itself using GET /Settlements/{id}, whose status carries the settlement state (cleared, hold, dispatched, or paid).

Note: Not every payment endpoint returns the same schema. GET /Merchants/{id}/payments and GET /Partners/{id}/payments return PaymentResponse, which carries all four linkage fields. GET /Terminals/{id}/payments returns a different schema, PaymentInfo, which carries settlementId, batchId, and batchStatus but does not carry batchPeriod. If your reconciliation logic depends on batchPeriod, source payments from the merchant or partner endpoint.

Payment settlement detail

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

Use payment settlement detail when you need to understand how an individual payment settled, which batch it belongs to, and the state of that batch. See Payment Settlement Detail.

Batches

Batches group payments for settlement processing and reconciliation.

Use Batches when you need to understand which payments were grouped together, review batch-level fee totals, and how they relate to a settlement record.

Deposits

Deposits represent funding activity associated with settlement.

Use Deposits when you need to confirm funded amounts, deposit status, deposit method, deposit fees, or the settlement record associated with a deposit.

Relationship to Reporting

Reporting focuses on payment history. Use Reporting APIs when you need lists of payments and transaction-level fields.

Settlement focuses on how completed payments were grouped, calculated, and funded. Use Settlement APIs when you need settlement fee breakdowns, batch relationships, payment-level settlement context, deposit information, and settlement status.

A common pattern is to use Reporting APIs to find the payments for a report or investigation, then use Settlement APIs to understand how those payments were settled and funded.

Files, exports, and API reporting

Bead exposes settlement, batch, deposit, and payment-level settlement data through APIs.

Most integrations should use the documented APIs for reconciliation. If a partner needs a custom settlement export or file delivery process, that should be handled as a separate implementation requirement with Bead.

Typical integration flows

Merchant settlement history

Goal: show settlement history for a merchant.

1. Identify the merchant in Bead.

2. Retrieve settlement records using GET /Merchants/{merchantId}/settlements.

3. Display settlement amount, status, settlement date, and net fundable amount.

4. Allow the user to select a settlement for batch and payment-level detail.

Payment-level settlement review

Goal: explain how a specific payment settled.

1. Start with a payment from Reporting APIs or a known payment identifier.

2. Retrieve the payment using GET /Merchants/{id}/payments and review settlementId, batchId, batchPeriod, and batchStatus on the PaymentResponse.

3. If settlementId is set, retrieve the settlement using GET /Settlements/{id} to review its status, fee totals, and net fundable amount. The settlement record, not the payment, is where settlement state lives.

4. Use GET /Settlements/{id}/batches for batch context and to connect the payment to the broader settlement.

Deposit reconciliation

Goal: reconcile funded deposits back to settlement activity.

1. Review the deposit record.

2. Use the related settlement information to identify the settlement activity behind the deposit.

3. Review batch and payment-level settlement information as needed.

4. Match deposit amount, settlement status, fees, and related payment activity to your internal ledger.

Residual and revenue-share reporting

Goal: calculate the revenue Bead retained on behalf of a partner for a settlement period for use in partner residual reporting.

1. Retrieve settlement records for the merchant and date range.

2. Review grossFundableAmount, totalTransactionFees, depositFees, totalFees, adjustments, netAdjustmentTotal, and netFundableAmount on each settlement. totalFees is the settlement's rolled-up fee total and netAdjustmentTotal is the net of all adjustments applied, so both are needed to follow the gross-to-net arithmetic without recomputing it yourself.

3. Compute retained revenue per merchant per period.

4. Apply your internal payout schedule to produce residual amounts.

See Residual Reporting for the full step-by-step pattern and field-level guidance.

Support investigation

Goal: answer a merchant or partner question about settlement timing or funding.

1. Use Reporting APIs to locate the original payment or group of payments.

2. Review settlementId, batchId, and batchStatus on the PaymentResponse to see which settlement and batch cover the payment and what state that batch is in.

3. Use GET /Settlements/{id} for the settlement's own status and settlementDate, and GET /Settlements/{id}/batches to understand the batch-level settlement event.

4. Review Deposits if the question is about funded movement to the destination account.

Next steps

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

• Use Residual Reporting to build partner residual reports.

• Use Payment Settlement Detail for payment-level settlement context and to trace payments through the settlement lifecycle.

• Use Batches when you need grouped payment batch records.

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

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

• Review Settlement status codes in the Settlement Status Codes when interpreting settlement states.

• Review Settlement currencies in the Settlement Currencies when interpreting settlement currency and tender information.