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 nameDescriptionFormatExample

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 row nameDescriptionFormatExample

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 nameDescriptionFormatExample

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

int_01978259-e06b-758c-8cd5-888cee9dd669

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 line nameDescriptionFormatExample

SettlementCurrency

The currency of the settlement file.

string

EUR

Guides

Read more about Mangopay Echo

Endpoints

POST Create a Settlement