Settlement file format requirements

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

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

string

50000 (500)

Currency

The currency of the transaction.

string

EUR

SettlementDate

The creation date of the settlement from the provider.

date (DD-MM-YYYY)

19-06-2025

ExternalProviderName

The supported third-party PSP processing the transaction.

string

Stripe

TotalSettlementFeesAmount

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.

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.

string

500

TotalNetSettlementAmount

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.

string

50000

SettlementCurrency

The currency of the settlement file.

string

EUR

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.

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.

string

150