Settlement file format requirements

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

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 name	Description	Format	Example
ExternalProviderReference	The unique identifier of the transaction at the provider level.	string	auth-stripe-633781e6-bb10-4484-8a29-ff6da7d7464a
ExternalTransactionType	The type of transaction using Mangopay’s accepted values: PAYMENT REFUND DISPUTE	string	PAYMENT
ExternalTransactionStatus	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. 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.	string	SETTLED
ExternalProcessingDate	The date on which the transaction was created.	date (DD-MM-YYYY)	19-06-2025
Amount	The amount of the transaction in the currency’s minor unit.	string	50000 (500)
Currency	The currency of the transaction.	string	EUR

Footer rows (mandatory)

Footer row name	Description	Format	Example
SettlementDate	The creation date of the settlement from the provider.	date (DD-MM-YYYY)	19-06-2025
ExternalProviderName	The name of the third-party PSP.	string	Stripe
TotalSettlementFeesAmount	The 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.	string	500
TotalSettlementAmount	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.	string	50000

Optional fields

Columns (optional)

Column name	Description	Format	Example
IntentId	The unique identifier of the associated Intent in Mangopay’s ecosystem.	string	int_01978259-e06b-758c-8cd5-888cee9dd669
ExternalPaymentMethod	The supported payment method used to process the transaction.	string	PAYPAL
ExternalInitialReference	The unique identifier of the original transaction authorization or capture at the acquirer’s level. Required only when ExternalTransactionType is REFUND or DISPUTE.	string	capture-stripe-d5fad854-117c-4b1a-bf15-d8e2846749c7
ExternalProviderFees	The amount of fees deducted by the provider from the transaction Amount in the currency’s minor unit.	string	150

Footer rows (optional)

Footer line name	Description	Format	Example
SettlementCurrency	The currency of the settlement file.	string	EUR

Related resources

Guides

Read more about Mangopay Echo

Endpoints

POST Create a Settlement