Skip to main content
This page describes the Mangopay format requirements of the CSV settlement file that your platform must upload via the Settlement API endpoints. See the Echo guide for more information on how to send settlement files and how Echo performs 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
Caution – Mandatory fields must not be emptyAll 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.

​
Example template

You can use this Example_Mangopay_Settlement_File.csv (click here to download), 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)

Column nameDescriptionFormatExample
ExternalProviderReferenceThe unique identifier of the transaction at the provider level.stringauth-stripe-633781e6-bb10-4484-8a29-ff6da7d7464a
ExternalTransactionTypeThe type of transaction using Mangopay’s accepted values:
  • PAYMENT
  • REFUND
  • DISPUTE
stringPAYMENT
ExternalTransactionStatusThe 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).
stringSETTLED
ExternalProcessingDateThe date on which the transaction was created.date (DD-MM-YYYY)19-06-2025
AmountThe 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: -		string50000 (500)
CurrencyThe currency of the transaction.stringEUR
Footer row nameDescriptionFormatExample
SettlementDateThe creation date of the settlement from the provider.date (DD-MM-YYYY)19-06-2025
ExternalProviderNameThe supported third-party PSP processing the transaction.stringStripe
TotalSettlementFeesAmountThe 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.
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.
string500
TotalNetSettlementAmountNet 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.string50000

​
Optional fields

​
Columns (optional)

Column nameDescriptionFormatExample
ExternalPaymentMethodThe supported payment method used to process the transaction.stringPAYPAL
ExternalInitialReferenceThe unique identifier of the original transaction authorization or capture at the acquirer’s level.Required only when ExternalTransactionType is REFUND or DISPUTE.stringcapture-stripe-d5fad854-117c-4b1a-bf15-d8e2846749c7
ExternalProviderFeesThe amount of fees deducted by the provider from the transaction Amount in the currency’s minor unit.
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.
string150
Footer line nameDescriptionFormatExample
SettlementCurrencyThe currency of the settlement file.stringEUR

Guides

Read more about Mangopay Echo

Endpoints

POST Create a Settlement