> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Settlement Object

The Settlement object represents the payment of Intents to Mangopay.

[Read more about Mangopay Echo](/guides/echo) **→**

### Attributes

<ResponseField name="SettlementId" type="string">
  The unique identifier of the Settlement.
</ResponseField>

<ResponseField name="Status" type="string">
  The status of the Settlement:

  * `PENDING_UPLOAD` – Settlement object and `UploadUrl` generated.
  * `UPLOADED` – Settlement file uploaded and received.
  * `CREATED` – Valid settlement file received, reconciliation 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.
  * `PENDING_FUNDS_RECEPTION` – Settlement file parsed and fully matched with Intents; waiting for funds to arrive on the escrow wallet.
  * `INSUFFICIENT_FUNDS` – Partial amount received: `FundsMissingAmount` shows the shortfall.
  * `RECONCILED` – Full settlement amount (`ActualSettlementAmount`) received on the escrow wallet.
  * `FAILED` – Settlement file rejected due to a technical error (e.g. format, timeout).
  * `CANCELLED` – Settlement file rejected due to a reconciliation error.

  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`.
</ResponseField>

<ResponseField name="CreationDate" type="Unix timestamp">
  The date and time the Settlement was created.
</ResponseField>

<ResponseField name="SettlementDate" type="Unix timestamp">
  The creation date of the settlement from the provider.
</ResponseField>

<ResponseField name="ExternalProviderName" type="string">
  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.
</ResponseField>

<ResponseField name="DeclaredIntentAmount" type="integer">
  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)
</ResponseField>

<ResponseField name="ExternalProcessorFeesAmount" type="integer">
  The total fees charged by the external provider
</ResponseField>

<ResponseField name="ActualSettlementAmount" type="integer">
  The total amount due to the platform, to be held in the escrow 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 escrow wallet.
</ResponseField>

<ResponseField name="FundsMissingAmount" type="integer">
  The difference between `ActualSettlementAmount` and the amount received on the escrow wallet
</ResponseField>

<ResponseField name="FileName" type="string">
  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.
</ResponseField>

<Panel>
  ```json Settlement object example theme={null}
  {
      "SettlementId": "int_stlmnt_01975582-2b19-7699-aaf3-a8167936254f",
      "Status": "RECONCILED",
      "CreationDate": 1749486283,
      "SettlementDate": 1749486162,
      "ExternalProviderName": "Stripe",
      "DeclaredIntentAmount": 10500,
      "ExternalProcessorFeesAmount": 500,
      "ActualSettlementAmount": 10000,
      "FundsMissingAmount": 0, 
      "FileName": "Example_File_Name_2025-12-16T15-03-15.csv"
  }
  ```
</Panel>