> ## 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.

# Cancel a Settlement

> Disregard a settlement file and stop it being processed

### Path parameters

<ParamField path="SettlementId" type="string" required>
  The unique identifier of the Settlement object.
</ParamField>

### Responses

<AccordionGroup>
  <Accordion title="200 - OK" defaultOpen>
    <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>
  </Accordion>
</AccordionGroup>

<ResponseExample>
  ```json 200 theme={null}
  {
      "SettlementId": "int_stlmnt_019b27af-db89-7114-9fe9-3c625519e1cb",
      "Status": "CANCELLED",
      "CreationDate": 1765897395,
      "SettlementDate": 1750291200,
      "ExternalProviderName": "STRIPE",
      "DeclaredIntentAmount": 0,
      "ExternalProcessorFeesAmount": 500,
      "ActualSettlementAmount": 49500,
      "FundsMissingAmount": 0,
      "FileName": "Example_Mangopay_Settlement_File_2026-02-03T09-08-57.csv"
  }
  ```
</ResponseExample>

<RequestExample>
  ```java Java theme={null}
  // in this case, the IdempotencyKey is null
  Settlement canceled = api.getSettlementApi().cancel(settlement.getSettlementId(), null);
  ```

  ```c# .NET theme={null}
  await Api.ApiSettlements.Cancel(settlement.SettlementId);
  ```

  ```javascript NodeJS theme={null}
  api.Settlements.cancel(settlement.SettlementId)
  ```

  ```php PHP theme={null}
  _api->Settlements->Cancel($settlement->SettlementId);
  ```

  ```py Python theme={null}
  cancelled = Settlement.cancel(settlement.settlement_id)
  ```

  ```ruby Ruby theme={null}
  MangoPay::Settlement.cancel(@settlement['SettlementId'])
  ```
</RequestExample>