> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mangopay.com/api-reference/settlements/list-settlements/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server.

# List all Settlements

GET https://api.sandbox.mangopay.com/v3.0/{ClientId}/payins/intents/settlements

Retrieve a paginated list of settlements, with optional filters for provider, currency, date range, and status.

Reference: https://docs.mangopay.com/api-reference/settlements/list-settlements

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token. If your platform is using a [proxy](/guides/sca/proxy-management) to take SCA-triggering action on behalf of users, you also need to integrate [mTLS authentication](/guides/sca/platform) and use the `api-mtls` base URL.

## Servers

- `https://api.sandbox.mangopay.com` (Sandbox, default)
- `https://api.mangopay.com` (Production)
- `https://api-mtls.sandbox.mangopay.com` (mTLS Sandbox)
- `https://api-mtls.mangopay.com` (mTLS Production)

## Request

### Path parameters

- `ClientId` (string, required) — Platform's API account identifier, associated with the API key.

### Query parameters

- `BeforeDate` (integer, optional) — The date before which the object was created (based on the object's `CreationDate` parameter). You can filter on a specific time range by using both the `AfterDate` and `BeforeDate` query parameters.
- `AfterDate` (integer, optional) — The date after which the object was created (based on the object's `CreationDate` parameter). You can filter on a specific time range by using both the `AfterDate` and `BeforeDate` query parameters.
- `Status` (string, optional) — **Allowed values:** `PENDING_UPLOAD`, `UPLOADED`, `CREATED`, `UNMATCHED`, `PARTIALLY_MATCHED`, `PENDING_FUNDS_RECEPTION`, `INSUFFICIENT_FUNDS`, `RECONCILED`, `FAILED`, `CANCELLED` The status of the Settlement. You can filter on multiple values by separating them with a comma.
- `ExternalProviderName` (string, optional) — The third-party PSP name to filter by.
- `Currency` (string, optional) — The three-letter ISO 4217 code of the currency to filter by.
- `page` (integer, optional) — Start value: `1` **Default value:** `1` Indicates the index of the page for the pagination.
- `per_page` (integer, optional) — Min. value: `1`; max. value: `100` **Default value:** `10` Indicates the number of items returned for each page of the pagination.

## Response

### 200

Success

- `list of SettlementResponse`

## Types

### SettlementResponse

- `SettlementId` (string, optional) — The unique identifier of the Settlement.
- `Status` (string, optional) — The status of the Settlement: - `PENDING_UPLOAD` – Settlement object and `SettlementFileUploadUrl` generated. - `UPLOADED` – A file was uploaded. - `CREATED` – The uploaded file was considered valid and reconciliation is in progress. A file is considered valid when it includes all required columns and a properly formatted footer. - `UNMATCHED` – None of the entries in the settlement file match the declared intents. - `PARTIALLY_MATCHED` – Settlement file parsed and some lines matched successfully. If at least one line is incorrectly formatted, the file remains in this status and does not progress further. Cancel the Settlement and re-submit. - `PENDING_FUNDS_RECEPTION` – Settlement file parsed and fully matched with Intents; waiting for funds to arrive on the technical wallet. - `INSUFFICIENT_FUNDS` – Partial amount received: `FundsMissingAmount` shows the shortfall. - `RECONCILED` – Full settlement amount (`ActualSettlementAmount`) received on the technical wallet. - `FAILED` – Settlement file rejected due to a technical error (e.g. format, timeout). - `CANCELLED` – Settlement file invalidated due to a reconciliation error. Once canceled, no further actions can be taken on this Settlement. If status becomes `FAILED` or `CANCELLED`, then call [POST Create a Settlement and secure URL for file upload](/api-reference/settlements/create-settlement) to create a new object. If the status becomes `UNMATCHED` or remains in `PARTIALLY_MATCHED` unexpectedly, then call [PUT Update a Settlement and generate a new upload URL](/api-reference/settlements/update-settlement) only a new URL is required for the existing `SettlementId`.
- `CreationDate` (integer, optional) — The date and time the Settlement was created.
- `SettlementDate` (integer, optional) — The creation date of the settlement from the provider.
- `ExternalProviderName` (string, optional) — The [supported third-party PSP](/api-reference/echo/supported-providers) processing the transaction. **Note:** The uppercase value is expected. The API returns the sentence-case value.
- `DeclaredIntentAmount` (integer, optional) — The total amount declared through Intent API calls, using the following calculation: (Sum of captured intents) - (Sum of refunded amounts) + (Sum of refund reversed amounts) - (Sum of `DISPUTED` disputes) + (Sum of `DISPUTED_WON` disputes)
- `ExternalProcessorFeesAmount` (integer, optional) — The total fees charged by the external provider
- `ActualSettlementAmount` (integer, optional) — The total amount due to the platform, to be held in the technical wallet. This amount corresponds to the `TotalNetSettlementAmount` of the settlement file. A negative amount results in this parameter being set to zero, indicating no incoming funds to the technical wallet.
- `FundsMissingAmount` (integer, optional) — The difference between `ActualSettlementAmount` and the amount received on the technical wallet
- `FileName` (string, optional) — The `FileName` submitted to the [POST Create a Settlement and generate upload URL](/api-reference/settlements/create-settlement) endpoint, with a timestamp of the Settlement creation date automatically appended by Mangopay.

## Examples

**Response**

```json
[
  {
    "SettlementId": "int_stlmnt_019b2756-c2f8-78a6-9a8f-1a0d354cef20",
    "Status": "RECONCILED",
    "CreationDate": 1765891663,
    "SettlementDate": 1750291200,
    "ExternalProviderName": "Stripe",
    "DeclaredIntentAmount": 50000,
    "ExternalProcessorFeesAmount": 500,
    "ActualSettlementAmount": 49500,
    "FundsMissingAmount": 0,
    "FileName": "Example_File_Name_2025-12-16T13-25.csv"
  },
  {
    "SettlementId": "int_stlmnt_019b27af-db89-7114-9fe9-3c625519e1cb",
    "Status": "PENDING_FUNDS_RECEPTION",
    "CreationDate": 1765897395,
    "SettlementDate": 1750377600,
    "ExternalProviderName": "Stripe",
    "DeclaredIntentAmount": 75000,
    "ExternalProcessorFeesAmount": 750,
    "ActualSettlementAmount": 74250,
    "FundsMissingAmount": 74250,
    "FileName": "Example_File_Name_2025-12-16T15-03.csv"
  }
]
```