# Payment Settlements

Payment settlements provide the payment-level view of settlement activity.

Use Payment Settlements when you need to understand how an individual payment settled, which merchant settlement it belongs to, the settled amount, the settlement status, and when funds became available.

Payment settlement records are useful for reconciliation, accounting, support investigations, and merchant-facing settlement detail.

#### When to use Payment Settlements

Use Payment Settlements when you need to:

* Review settlement detail for individual payments.
* Connect a payment to a merchant settlement.
* Check settlement status for one or more payments.
* Review settled amount, currency, and availability timing.
* Build reconciliation reports that combine payment and settlement data.
* Investigate payment-level settlement exceptions.
* Support merchant or partner questions about how a specific payment settled.

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

#### How it works

A payment settlement record connects a completed payment to settlement activity.

A typical payment settlement review flow is:

1. Start with a merchant, payment, merchant settlement, or date range.
2. Retrieve payment settlement records using the relevant endpoint.
3. Review the payment ID, settlement amount, settlement status, and available time.
4. Use the merchant settlement ID to connect the payment to a merchant-level settlement event.
5. Use Batches or Deposits when you need to reconcile settlement activity to grouped payments or funded movement.

#### Available endpoints

| Scope                                       | Path                                                          | Description                                                                                   |
| ------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Merchant payment settlement lines           | `/MerchantSettlements/merchant-payment-settlements/merchant`  | Returns merchant payment settlement records for a merchant.                                   |
| Payment settlements by merchant             | `/Merchants/{merchantId}/payment-settlements`                 | Returns payment settlement records for a merchant, with optional settlement status filtering. |
| Payments and settlement lines by date range | `/MerchantSettlements/merchant/between`                       | Returns payment data and merchant payment settlement data for a merchant and time window.     |
| Settlement batch payment detail             | `/MerchantSettlements/settlement-info/{merchantSettlementId}` | Returns payment-level detail for a specific merchant settlement.                              |
| Payment IDs for a merchant settlement       | `/MerchantSettlements/payment-ids/merchant-settlement`        | Returns payment IDs associated with a merchant settlement.                                    |

#### Query parameters

Common query parameters include:

* `merchantId`
* `merchantSettlementId`
* `status`
* `startTime`
* `endTime`
* `page`
* `pageSize`
* `sortByDirection`

`page` defaults to `0` on most settlement endpoints. `pageSize` defaults to `10` where specified. `sortByDirection` supports `ascending` and `descending`.

Use the merchant ID when reviewing settlement activity for a merchant. Use the merchant settlement ID when drilling into a known settlement. Use date range parameters when building reconciliation reports for a specific settlement window.

#### Payment settlement objects

Several related objects appear in payment settlement responses.

**Merchant payment settlement**

A merchant payment settlement describes how a specific payment settled for a merchant.

| Field                   | Type              | Description                                                                     |
| ----------------------- | ----------------- | ------------------------------------------------------------------------------- |
| `id`                    | string or null    | Unique merchant payment settlement identifier.                                  |
| `paymentId`             | string            | Payment associated with this settlement line.                                   |
| `merchantId`            | string            | Merchant associated with the payment settlement.                                |
| `merchantLocationId`    | string            | Location associated with the payment settlement.                                |
| `terminalId`            | string            | Terminal associated with the payment settlement.                                |
| `amount`                | object            | Settled amount for the payment. Uses amount, amount precision, and currency ID. |
| `merchantSettlementId`  | string or null    | Merchant settlement associated with this payment settlement, when assigned.     |
| `settlementStartTime`   | date-time or null | Start of the settlement window.                                                 |
| `settlementEndTime`     | date-time or null | End of the settlement window.                                                   |
| `availableTime`         | date-time or null | Time funds were or are expected to be available.                                |
| `settlementType`        | string            | Settlement delivery type. Values include `ach` and `wire`.                      |
| `settlementBeneficiary` | object            | Beneficiary information for the settlement.                                     |
| `status`                | string            | Current merchant payment settlement status.                                     |
| `transfers`             | array of strings  | Transfer identifiers associated with the settlement line.                       |
| `created`               | date-time or null | Date and time the record was created.                                           |
| `updated`               | date-time or null | Date and time the record was last updated.                                      |

**Payment settlement**

A payment settlement provides a payment-centered settlement view.

| Field                     | Type              | Description                                                                 |
| ------------------------- | ----------------- | --------------------------------------------------------------------------- |
| `id`                      | string or null    | Unique payment settlement identifier.                                       |
| `paymentId`               | string or null    | Payment associated with the settlement record.                              |
| `merchantId`              | string            | Merchant associated with the payment.                                       |
| `merchantLocationId`      | string            | Location associated with the payment.                                       |
| `terminalId`              | string            | Terminal associated with the payment.                                       |
| `settleableAmount`        | object            | Amount available to settle. Uses amount, amount precision, and currency ID. |
| `exchangeLossGain`        | object            | Exchange gain or loss amount, when applicable.                              |
| `merchantTransactions`    | array             | Conversion or transaction records associated with settlement.               |
| `settlementAvailableTime` | date-time or null | Time funds were or are expected to be available.                            |
| `settlementStatus`        | string            | Current payment settlement status.                                          |
| `created`                 | date-time or null | Date and time the record was created.                                       |
| `updated`                 | date-time or null | Date and time the record was last updated.                                  |

**Payment with merchant payment settlement**

Some endpoints return payment data and merchant payment settlement data together.

This response includes:

| Field                       | Type   | Description                                                     |
| --------------------------- | ------ | --------------------------------------------------------------- |
| `payment`                   | object | Payment record.                                                 |
| `merchantPaymentSettlement` | object | Merchant payment settlement record associated with the payment. |

Use this response when you want payment details and settlement-line details in the same result set.

#### Amount fields

Settlement amount fields use an amount object.

| Field             | Type    | Description                                   |
| ----------------- | ------- | --------------------------------------------- |
| `amount`          | number  | Numeric amount.                               |
| `amountPrecision` | integer | Number of decimal places used for the amount. |
| `currencyId`      | integer | Currency identifier for the amount.           |

#### Merchant payment settlement status

Merchant payment settlement status indicates the state of a payment-level settlement line.

Supported values include:

* `created`
* `pending`
* `processing`
* `completed`
* `error`

Use this status when reviewing merchant payment settlement records and payment-level settlement lines.

#### Payment settlement status

Payment settlement status indicates the settlement state from the payment perspective.

Supported values include:

* `storing`
* `pending`
* `settling`
* `completed`
* `cancelled`
* `failed`

Use this status when filtering or reviewing payment settlement records from `/Merchants/{merchantId}/payment-settlements`.

#### Settlement type

Settlement type identifies the delivery method for the payment settlement.

Supported values include:

* `ach`
* `wire`

#### Settlement beneficiary

Settlement beneficiary identifies who receives the settlement.

The beneficiary object includes:

| Field       | Type   | Description                                            |
| ----------- | ------ | ------------------------------------------------------ |
| `type`      | string | Beneficiary type. Values include `self` and `partner`. |
| `partnerId` | string | Partner associated with the beneficiary.               |

#### Choosing the right endpoint

Use `/MerchantSettlements/merchant-payment-settlements/merchant` when you want merchant payment settlement lines for a merchant and do not need the full payment object in the same response.

Use `/Merchants/{merchantId}/payment-settlements` when you want payment settlement records for a merchant and want to filter by payment settlement status.

Use `/MerchantSettlements/merchant/between` when you want payments and merchant payment settlement records together for a merchant and time window.

Use `/MerchantSettlements/settlement-info/{merchantSettlementId}` when you start from a specific merchant settlement and need the payment-level breakdown.

Use `/MerchantSettlements/payment-ids/merchant-settlement` when you only need payment IDs for a merchant settlement and will retrieve payment details separately.

#### Relationship to other Settlement pages

Payment Settlements are part of the broader Settlement model.

Use Payment Settlements when you need payment-level settlement detail. Use Merchant Settlements when you need the merchant-level settlement event. Use Batches when you need to understand grouped payment batches. Use Deposits when you need to confirm funded movement tied to a settlement.

A common pattern is:

1. Use [Reporting](/reporting.md) APIs to find completed payments.
2. Use [Payment Settlements](/settlement/payment-settlements.md) to review payment-level settlement detail.
3. Use [Merchant Settlements](/settlement/merchant-settlements.md) to connect payment-level records to merchant-level settlement events.
4. Use [Batches](/settlement/batches.md) to understand grouped payment activity.
5. Use [Deposits](/settlement/deposits.md) to confirm funded movement and deposit status.

#### Typical integration flows

**Review settlement detail for a payment**

Goal: explain how a specific payment settled.

High level steps:

1. Start with a payment ID or payment history result.
2. Retrieve payment settlement detail for the merchant.
3. Match the payment ID to the relevant settlement record.
4. Review settlement amount, settlement status, available time, and merchant settlement ID.

**Reconcile a merchant settlement to payments**

Goal: show the payment-level detail behind a merchant settlement.

High level steps:

1. Start with a merchant settlement ID.
2. Retrieve payment settlement detail for that settlement.
3. Review each payment, settled amount, status, and available time.
4. Match payment-level totals to the merchant settlement and internal ledger.

**Build a payment-level settlement report**

Goal: build a report that combines payment data and settlement data.

High level steps:

1. Identify the merchant and date range.
2. Retrieve payments and merchant payment settlement records for that time window.
3. Display payment identifiers, payment status, settlement amount, settlement status, and available time.
4. Use merchant settlement IDs to group rows by settlement event.

**Investigate settlement exceptions**

Goal: identify payment-level settlement items that need review.

High level steps:

1. Retrieve payment settlement records for the merchant.
2. Filter by non-completed settlement statuses.
3. Review payment ID, settlement status, and updated timestamp.
4. Use the merchant settlement ID, batch data, or deposit data for additional context.

#### Next steps

* Use [Merchant Settlements](/settlement/merchant-settlements.md) for merchant-level settlement events.
* Use [Batches](/settlement/batches.md) when you need grouped payment batch records.
* Use [Deposits](/settlement/deposits.md) when you need funded movement and deposit status.
* Use [Reporting](/reporting.md) APIs when you need payment history before reviewing settlement.
* Use [Settlement status codes](/reference-guide/enumerations-and-schemas/settlement-status-codes.md) in the Reference Guide when interpreting settlement states.


---

# Agent Instructions: 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:

```
GET https://developers.bead.xyz/settlement/payment-settlements.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.