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

# Settlement file format requirements

This page describes the Mangopay format requirements of the CSV settlement file that your platform must upload via the [Settlement API endpoints](/api-reference/settlements/settlement-object).

See the Echo guide for more information on [how to send settlement files](/guides/echo#how-to-send-a-settlement-file-to-mangopay) and how Echo performs [reconciliation](/guides/echo#reconciliation).

The CSV file contains:

* Transaction data – Header columns and a row for each transaction included in the settlement file
* A single empty row (string of commas)
* Footer rows – Summary data with header rows and a single value for each

<Warning>
  **Caution – Mandatory fields must not be empty**

  All mandatory fields must be present and not empty in every row or the file will be rejected. The parser identifies columns by their headers, not their position.

  Optional fields (transaction data or summary footer) can be empty.
</Warning>

### Example template

You can use this **Example\_Mangopay\_Settlement\_File.csv** ([click here to download](https://docs.mangopay.com/api-reference/settlements/Example_Mangopay_Settlement_File.csv)), which contains the correct column and row labels and example data for 3 transactions. Remove the example data lines before generating your own file.

## File requirements

* File type: `.csv`
* Delimiter: Comma `,`
* Max. file size: TBD

## Mandatory fields

### Columns (mandatory)

<table>
  <thead>
    <tr>
      <th class="header">Column name</th>
      <th class="header">Description</th>
      <th class="header">Format</th>
      <th class="header">Example</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td class="table-content">
        `ExternalProviderReference`
      </td>

      <td class="table-content">
        The unique identifier of the transaction at the provider level.
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        `auth-stripe-633781e6-bb10-4484-8a29-ff6da7d7464a`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `ExternalTransactionType`
      </td>

      <td class="table-content">
        The type of transaction using Mangopay's accepted values:

        * `PAYMENT`
        * `REFUND`
        * `DISPUTE`
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        `PAYMENT`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `ExternalTransactionStatus`
      </td>

      <td class="table-content">
        The status of the transaction. The accepted values listed can only apply to the `ExternalTransactionType` mentioned:

        * `SETTLED` – `PAYMENT` successfully processed: funds are expected to be received (positive `Amount`).
        * `REFUNDED` – `REFUND` fully processed: funds were returned to the buyer (negative `Amount`).
        * `REFUND_REVERSED` – `REFUND` processed but reversed: funds were returned to the platform (positive `Amount`).
        * `DISPUTED` – Funds deducted due to a `DISPUTE`: not available for settlement (negative `Amount`).
        * `DEFENDED` – Funds temporarily returned to the platform as part of the `DISPUTE` defense process (negative `Amount`).
        * `DISPUTED_WON` – `DISPUTE` resolved in favor of the platform (positive `Amount`).
        * `DISPUTED_LOST` – `DISPUTE` resolved against the platform: funds permanently withdrawn to buyer (negative `Amount`).
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        `SETTLED`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `ExternalProcessingDate`
      </td>

      <td class="table-content">
        The date on which the transaction was created.
      </td>

      <td class="table-content">
        date (DD-MM-YYYY)
      </td>

      <td class="table-content">
        `19-06-2025`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `Amount`
      </td>

      <td class="table-content">
        The amount of the transaction in the currency's minor unit. The `Amount` figure is positive or negative depending on the `ExternalTransactionStatus`:

        * `SETTLED` - Positive
        * `REFUNDED` - Negative
        * `REFUND_REVERSED` - Positive
        * `DISPUTED` - Negative
        * `DEFENDED` - Negative
        * `DISPUTED_WON` - Positive
        * `DISPUTED_LOST` - Negative

        Therefore:

        * A positive `Amount` is expected to be received by Mangopay and thus credited to the settled amount during Echo's reconciliation process.
        * A negative `Amount` is expected to be retained by the third-party PSP and thus debited from the settled amount during Echo's reconciliation process.

        A negative figure must be declared using a hyphen-dash: `-`
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        `50000` (500)
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `Currency`
      </td>

      <td class="table-content">
        The currency of the transaction.
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        `EUR`
      </td>
    </tr>
  </tbody>
</table>

### Footer rows (mandatory)

<table>
  <thead>
    <tr>
      <th class="header">Footer row name</th>
      <th class="header">Description</th>
      <th class="header">Format</th>
      <th class="header">Example</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td class="table-content">
        `SettlementDate`
      </td>

      <td class="table-content">
        The creation date of the settlement from the provider.
      </td>

      <td class="table-content">
        date (DD-MM-YYYY)
      </td>

      <td class="table-content">
        `19-06-2025`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `ExternalProviderName`
      </td>

      <td class="table-content">
        The [supported third-party PSP](/api-reference/echo/supported-providers) processing the transaction.
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        `Stripe`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `TotalSettlementFeesAmount`
      </td>

      <td class="table-content">
        The total amount of fees taken by the provider from the settlement in the currency's minor unit. This amount matches the sum of all `ExternalProviderFees` values in the file, if they are provided.

        <br />

        The field accept a negative or positive value:

        * A negative value (e.g., `-500` for -5.00) is a debit. This is a standard fee or cost charged by the PSP.
        * A positive value (e.g., `125` for 1.25) is a credit. This is a fee or cost being refunded or credited to the platform by the PSP.
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        `500`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `TotalNetSettlementAmount`
      </td>

      <td class="table-content">
        Net settlement amount in the currency's minor unit, which must be the sum of the `Amount` values of all transaction lines, minus the `TotalSettlementFeesAmount`. The `Amount` values must be declared as positive or negative as described depending on the `ExternalTransactionStatus`.
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        `50000`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `SettlementCurrency`
      </td>

      <td class="table-content">
        The currency of the settlement file.
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        `EUR`
      </td>
    </tr>
  </tbody>
</table>

## Optional fields

### Columns (optional)

<table>
  <thead>
    <tr>
      <th class="header">Column name</th>
      <th class="header">Description</th>
      <th class="header">Format</th>
      <th class="header">Example</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td class="table-content">
        `ExternalPaymentMethod`
      </td>

      <td class="table-content">
        The [supported payment method](/api-reference/echo/supported-payment-methods) used to process the transaction.
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        `PAYPAL`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `ExternalInitialReference`
      </td>

      <td class="table-content">
        The unique identifier of the original transaction authorization or capture at the acquirer's level.

        Required only when `ExternalTransactionType` is `REFUND` or `DISPUTE`.
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        `capture-stripe-d5fad854-117c-4b1a-bf15-d8e2846749c7`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `ExternalProviderFees`
      </td>

      <td class="table-content">
        The amount of fees deducted by the provider from the transaction `Amount` in the currency's minor unit.

        <br />

        The field accept a negative or positive value:

        * A negative value (e.g., `-500` for -5.00) is a debit. This is a standard fee or cost charged by the PSP.
        * A positive value (e.g., `125` for 1.25) is a credit. This is a fee or cost being refunded or credited to the platform by the PSP.
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        `150`
      </td>
    </tr>
  </tbody>
</table>

## Related resources

<CardGroup col={2}>
  <Card title="Guides" href="/guides/echo">
    Read more about Mangopay Echo
  </Card>

  <Card title="Endpoints" href="/api-reference/settlements/create-settlement">
    POST Create a Settlement
  </Card>
</CardGroup>