> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/settlement/payment-settlement-detail.md).

# 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](/settlement/settlements.md) for period-level fee totals, adjustments, and net fundable amount.
* Use [Batches](/settlement/batches.md) to review grouped payment activity and verify fee rollups.
* Use [Deposits](/settlement/deposits.md) to confirm funded bank movement tied to a settlement.
* Use [Reporting](/reporting.md) when you need payment history before reviewing settlement.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.bead.xyz/settlement/payment-settlement-detail.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.