This page describes the Mangopay format requirements of the CSV settlement file that your platform must upload to the POST Create a Settlement endpoint. 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 CSV file (right click and Save as…), 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
There are no requirements for the file name – you can name your file how you like.

​
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.
  • REFUNDED – REFUND fully processed: funds were returned to the buyer.
  • REFUND_REVERSED – REFUND processed but reversed: funds were returned to the platform.
  • DISPUTED – Funds deducted due to a DISPUTE: not available for settlement.
  • DEFENDED – Funds temporarily returned to the platform as part of the DISPUTE defense process.
  • DISPUTED_WON – DISPUTE resolved in favor of the platform.
  • DISPUTED_LOST – DISPUTE resolved against the platform: funds permanently withdrawn to buyer.
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.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 match the sum of all ExternalProviderFees values in the file, if they are provided.string500
TotalSettlementAmountNet settlement amount in the currency’s minor unit, which must be the sum of the Amount values of all transaction lines, minus the TotalSettlementFeesAmount.string50000

​
Optional fields

​
Columns (optional)

Column nameDescriptionFormatExample
IntentIdThe unique identifier of the associated Intent in Mangopay’s ecosystem.stringint_01978259-e06b-758c-8cd5-888cee9dd669
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.string150
Footer line nameDescriptionFormatExample
SettlementCurrencyThe currency of the settlement file.stringEUR

Guides

Read more about Mangopay Echo

Endpoints

POST Create a Settlement