Create a Report

Generate a reporting service report

POST /v2.01/{ClientId}/reporting/reports

COLLECTED_FEES

{
    "Tag": "Created using the Mangopay API Postman collection",
    "DownloadFormat": "CSV",
    "ReportType": "COLLECTED_FEES",
    "DateRangeBy": "ExecutionDate",
    "AfterDate": 1740787200,
    "BeforeDate": 1743544740,
    "Filters": {
        "Currency": "EUR"
    }
}

COLLECTED_FEES

{
    "Id": "report_01JVVQDDZ4AT67C2W62ZNK2DC2",
    "Tag": "Created using the Mangopay API Postman collection",
    "CreationDate": 1747908474,
    "ReportDate": null,
    "Status": "PENDING",
    "ResultCode": null,
    "ResultMessage": null,
    "DownloadFormat": "CSV",
    "DownloadURL": null,
    "ReportType": "COLLECTED_FEES",
    "Sort": "CreationDate:DESC",
    "DateRangeBy": "ExecutionDate",
    "AfterDate": 1740787200,
    "BeforeDate": 1743544740,
    "Filters": {
        "Currency": "EUR"
    },
    "Columns": [
        {
            "Name": "ClientId",
            "IsDefault": true
        },
        {
            "Name": "TransactionId",
            "IsDefault": true
        },
        {
            "Name": "CreationDate",
            "IsDefault": true
        },
        {
            "Name": "ExecutionDate",
            "IsDefault": true
        },
        {
            "Name": "AuthorId",
            "IsDefault": true
        },
        {
            "Name": "DebitedWalletId",
            "IsDefault": true
        },
        {
            "Name": "CreditedWalletId",
            "IsDefault": true
        },
        {
            "Name": "CreditedFundsCurrency",
            "IsDefault": true
        },
        {
            "Name": "CreditedFundsAmount",
            "IsDefault": true
        },
        {
            "Name": "DebitedFundsCurrency",
            "IsDefault": true
        },
        {
            "Name": "DebitedFundsAmount",
            "IsDefault": true
        },
        {
            "Name": "FeesAmount",
            "IsDefault": true
        },
        {
            "Name": "FeesCurrency",
            "IsDefault": true
        },
        {
            "Name": "Type",
            "IsDefault": true
        },
        {
            "Name": "Nature",
            "IsDefault": true
        },
        {
            "Name": "PaymentType",
            "IsDefault": true
        },
        {
            "Name": "Tag",
            "IsDefault": true
        }
    ]
}

This endpoint generates a report from Mangopay’s Reporting Service, which is replacing the legacy report types (read the guide).

There are 2 reports (indicated by ReportType) that may be useful to all platforms: USER_WALLET_TRANSACTIONS and COLLECTED_FEES.

There are 4 ReportType that are designed to support platforms using Echo, Mangopay solution for integrations working with third-party PSPs: ECHO_INTENT, ECHO_INTENT_ACTION, ECHO_SETTLEMENT, ECHO_SPLIT.

Each ReportType has different available Columns and Filters.

Note – Report expires after 31 days

A Reporting Service report expires after 31 days, at which point it can no longer be downloaded. On expiry, the report’s Status becomes EXPIRED and the DownloadURL becomes null.

You can generate a new report with the same filters and dates.

Body parameters

Tag · string

Max. length: 255 characters

Custom data that you can add to this object.

For reports, this parameter can be useful to give the report a name.

DownloadFormat · string · required

Possible values: CSV

The format of the report file.

ReportType · string · required

Possible values: COLLECTED_FEES, USER_WALLET_TRANSACTIONS, ECHO_INTENT, ECHO_INTENT_ACTION, ECHO_SETTLEMENT, ECHO_SPLIT.

The type of the report. Each ReportType has different available Columns and Filters.

Useful for all platforms:

• USER_WALLET_TRANSACTIONS – All successful transactions crediting or debiting user wallets: pay-ins, transfers, conversions, and payouts, as well as refunds of all types and repudiations (from chargebacks).
• COLLECTED_FEES– Detail of transactions crediting or debiting the fees wallet: successful transactions of all types (pay-ins, transfers, refunds, payouts, etc.) that have a positive or negative fees amount.

Useful for platforms using Echo, Mangopay’s solution for integrations working with third-party PSPs:

• ECHO_INTENT – Summary of all intents declared during the selected period, detailing the total funds expected to enter the platform’s technical wallets.
• ECHO_INTENT_ACTION – Summary of all operations related to intents processed during the selected period, detailing the expected money movements to be escrowed — including payments, refunds, refund reversals, and chargebacks.
• ECHO_SETTLEMENT – Summary of all settlement files uploaded during the selected period to initiate the reconciliation process, confirming the expected money movements to be escrowed.
• ECHO_SPLIT – Summary of all splits related to intents during the selected period, detailing the transfer of funds to the declared destination.

Sort · string

Possible values: CreationDate:ASC, CreationDate:DESC

Default value: CreationDate:DESC

The sort direction based on transaction creation date.

DateRangeBy · string | null

Possible values: CreationDate, ExecutionDate

Default value: CreationDate

The date to which BeforeDate and AfterDate apply. The DateRangeBy property can only be sent on USER_WALLET_TRANSACTIONS and COLLECTED_FEES reports. It is returned null for other types.

The ExecutionDate value is likely to be more useful, because this is the date and time that the transaction Status became SUCCEEDED. Note also that these reports only contain successful transactions.

AfterDate · Unix timestamp · required

Possible values: Any past date and time up 24 months ago that is earlier than the BeforeDate by less than 12 months

The date and time after which the report’s transaction was created, based on the transaction’s CreationDate.

BeforeDate · Unix timestamp · required

Possible values: Any past date and time up 24 months ago that is later than the AfterDate by less than 12 months

The date and time before which the report’s transaction was created, based on the transaction’s CreationDate.

Filters · object

The filers to apply. Each ReportType has different available filters:

COLLECTED_FEES

The Currency filter is available. If not specified, the report contains data on all currencies.

Hide properties

Currency · string

The currency of the DebitedFunds, CreditedFunds, or Fees of the transactions.

USER_WALLET_TRANSACTIONS

The Currency, UserId, and WalletId filters are available, and can be used alone or in combination, in which case the report data satisfies both filters.

• UserId and Currency – Report contains all transactions (credited or debited) in the currency where UserId is the AuthorId
• UserId and WalletId – Report contains all transactions (credited or debited) in all currencies where the UserId is specified as the DebitedWalletId or CreditedWalletId. Caution: If the WalletId is not a wallet owned by the UserId, then the report will be empty.

The Currency and WalletId cannot be used together.

If no Filters are specified, the report contains all successful transactions crediting or debiting all user wallets.

Hide properties

Currency · string

The currency of the DebitedFunds, CreditedFunds, or Fees of the transactions.

UserId · string

The unique identifier of the user referenced as the AuthorId or CreditedUserId of the transaction.

WalletId · string

The unique identifier of the wallet referenced as the DebitedWalletId or CreditedWalletId of the transaction.

ECHO_INTENT

The ECHO_INTENT and ECHO_INTENT_ACTION reports have the same filters, which can be used in any combination.

Hide properties

Type · string

The type of Intent (as indicated in the settlement file): PAYIN, REFUND, DISPUTE

Status · string

The Status of the Intent: AUTHORIZED, PARTIALLY_CAPTURED, CAPTURED, CANCELED, REFUNDED, REFUND_REVERSED, DISPUTED, DEFENDED, DISPUTED_WON, DISPUTED_LOST

PaymentMethod · string

The payment method of the Intent: one of the supported values of the ExternalProviderPaymentMethod

ECHO_INTENT_ACTION

The ECHO_INTENT and ECHO_INTENT_ACTION reports have the same filters, which can be used in any combination.

Hide properties

Type · string

The type of Intent (as indicated in the settlement file): PAYIN, REFUND, DISPUTE

Status · string

The Status of the Intent: AUTHORIZED, PARTIALLY_CAPTURED, CAPTURED, CANCELED, REFUNDED, REFUND_REVERSED, DISPUTED, DEFENDED, DISPUTED_WON, DISPUTED_LOST

PaymentMethod · string

The payment method of the Intent: one of the supported values of the ExternalProviderPaymentMethod

ECHO_SETTLEMENT

On the ECHO_SETTLEMENT report, the following filters can be used (alone or together).

Hide properties

Status · string

The Status of the Settlement: UPLOADED, CREATED, UNMATCHED, PARTIALLY_MATCHED, PENDING_FUNDS_RECEPTION, INSUFFICIENT_FUNDS, RECONCILED, FAILED

ExternalProviderName · string

The supported third-party PSP processing the transaction.

ECHO_SPLIT

On the ECHO_SPLIT report, the the following filters can be used (alone or in combination).

Hide properties

Status · string

The Status of the Split: CREATED, PENDING_FUNDS_RECEPTION, AVAILABLE, PENDING, COMPLETED, REJECTED, FAILED , REVERSED

IntentId · string

The unique identifier of the related Intent.

Caution: There is no validation that the IntentId is valid.

Scheduled · boolean

Whether or not the TransferDate was sent (in either the Intent or the Split), regardless of the Status of the Split.

Columns · array

Possible values: The columns listed in the Reports guide, which differ according to the report type.

Default values: The default columns listed in the Reports guide, which differ according to the report type.

The data columns to be included in the report.

Responses

200 - Response parameters

Id · string

Max length: 128 characters (see data formats for details)

The unique identifier of the object.

Tag · string

Max. length: 255 characters

Custom data that you can add to this object.

For reports, this parameter can be useful to give the report a name.

CreationDate · Unix timestamp

The date and time at which the object was created.

ReportDate · Unix timestamp | null

The date and time at which the report was generated.

Status · string

Returned values: PENDING, READY_FOR_DOWNLOAD, FAILED, EXPIRED

The status of the report:

• PENDING – The report is being generated.
• READY_FOR_DOWNLOAD – The report has been created, and can be downloaded.
• FAILED – The report cannot be generated.
• EXPIRED – The report was created, but is no longer available for download (it can be re-run to be downloaded again with fresh data).

ResultCode · string

The code indicating the result of the operation. This information is mostly used to handle errors or for filtering purposes.

ResultMessage · string

The explanation of the result code.

DownloadFormat · string

Returned values: CSV

The format in which the report is going to be downloaded.

DownloadURL · string | null

The URL at which the report file can be downloaded when the Status is GENERATED.

ReportType · string

Possible values: COLLECTED_FEES, USER_WALLET_TRANSACTIONS, ECHO_INTENT, ECHO_INTENT_ACTION, ECHO_SETTLEMENT, ECHO_SPLIT.

The type of the report. Each ReportType has different available Columns and Filters.

Useful for all platforms:

• USER_WALLET_TRANSACTIONS – All successful transactions crediting or debiting user wallets: pay-ins, transfers, conversions, and payouts, as well as refunds of all types and repudiations (from chargebacks).
• COLLECTED_FEES– Detail of transactions crediting or debiting the fees wallet: successful transactions of all types (pay-ins, transfers, refunds, payouts, etc.) that have a positive or negative fees amount.

Useful for platforms using Echo, Mangopay’s solution for integrations working with third-party PSPs:

• ECHO_INTENT – Summary of all intents declared during the selected period, detailing the total funds expected to enter the platform’s technical wallets.
• ECHO_INTENT_ACTION – Summary of all operations related to intents processed during the selected period, detailing the expected money movements to be escrowed — including payments, refunds, refund reversals, and chargebacks.
• ECHO_SETTLEMENT – Summary of all settlement files uploaded during the selected period to initiate the reconciliation process, confirming the expected money movements to be escrowed.
• ECHO_SPLIT – Summary of all splits related to intents during the selected period, detailing the transfer of funds to the declared destination.

AfterDate · Unix timestamp

Possible values: Any date and time (before the BeforeDate) between the present and 24 months ago.

The date and time after which the report’s transaction was created, based on the transaction’s CreationDate.

Note: The period between the AfterDate and the BeforeDate cannot exceed 12 months.

BeforeDate · Unix timestamp

Possible values: Any date and time (after the AfterDate) between the present and 24 months ago.

The date and time before which the report’s transaction was created, based on the transaction’s CreationDate.

Note: The period between the AfterDate and the BeforeDate cannot exceed 12 months.

Filters · object

The filters sent in the request. Different filters are available for each ReportType.

Columns · array (string)

Possible values: The columns listed in the Reports guide, which differ according to the report type.

Default values: The default columns listed in the Reports guide, which differ according to the report type.

The data columns to be included in the report.

400 - User wallet transactions – WalletId and Currency filters can't be combined

{
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Id": "48455ac1-cdb1-4d15-b1e0-510a38770bd1",
    "Date": 1748869280.0,
    "errors": {
        "UserId & Currency": "User Id or Wallet Id has to be provided in filters"
    }
}

400 - Max. 12 months between AfterDate and BeforeDate

{
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Id": "552b8151-ee15-4aaa-886c-aaf2757aea76",
    "Date": 1748009585.0,
    "errors": {
        "Report": "Max 12 months between AfterDate and BeforeDate."
    }
}

Invalid Column for ReportType

{
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Id": "a82b56d6-2471-4b51-8480-af7e24cb695e",
    "Date": 1748869101.0,
    "errors": {
        "Report": "Unknown columns were found in the list: Amount, Report Columns: ClientId, TransactionId, CreationDate, CreationDate:ISO, ExecutionDate, ExecutionDate:ISO, AuthorId, CreditedUserId, DebitedFundsAmount, DebitedFundsCurrency, CreditedFundsAmount, CreditedFundsCurrency, FeesAmount, FeesCurrency, Type, Nature, CreditedWalletId, DebitedWalletId, BankAccountId, PreauthorizationId, BankWireRef, CardId, CardAlias, CardType, CardCountry, CardExpirationDate, Culture, DeclaredDebitedFundsAmount, DeclaredDebitedFundsCurrency, DeclaredFeesAmount, DeclaredFeesCurrency, ExecutionType, PaymentType, WireReference"
    }
}

COLLECTED_FEES

{
    "Id": "report_01JVVQDDZ4AT67C2W62ZNK2DC2",
    "Tag": "Created using the Mangopay API Postman collection",
    "CreationDate": 1747908474,
    "ReportDate": null,
    "Status": "PENDING",
    "ResultCode": null,
    "ResultMessage": null,
    "DownloadFormat": "CSV",
    "DownloadURL": null,
    "ReportType": "COLLECTED_FEES",
    "Sort": "CreationDate:DESC",
    "DateRangeBy": "ExecutionDate",
    "AfterDate": 1740787200,
    "BeforeDate": 1743544740,
    "Filters": {
        "Currency": "EUR"
    },
    "Columns": [
        {
            "Name": "ClientId",
            "IsDefault": true
        },
        {
            "Name": "TransactionId",
            "IsDefault": true
        },
        {
            "Name": "CreationDate",
            "IsDefault": true
        },
        {
            "Name": "ExecutionDate",
            "IsDefault": true
        },
        {
            "Name": "AuthorId",
            "IsDefault": true
        },
        {
            "Name": "DebitedWalletId",
            "IsDefault": true
        },
        {
            "Name": "CreditedWalletId",
            "IsDefault": true
        },
        {
            "Name": "CreditedFundsCurrency",
            "IsDefault": true
        },
        {
            "Name": "CreditedFundsAmount",
            "IsDefault": true
        },
        {
            "Name": "DebitedFundsCurrency",
            "IsDefault": true
        },
        {
            "Name": "DebitedFundsAmount",
            "IsDefault": true
        },
        {
            "Name": "FeesAmount",
            "IsDefault": true
        },
        {
            "Name": "FeesCurrency",
            "IsDefault": true
        },
        {
            "Name": "Type",
            "IsDefault": true
        },
        {
            "Name": "Nature",
            "IsDefault": true
        },
        {
            "Name": "PaymentType",
            "IsDefault": true
        },
        {
            "Name": "Tag",
            "IsDefault": true
        }
    ]
}

COLLECTED_FEES

{
    "Tag": "Created using the Mangopay API Postman collection",
    "DownloadFormat": "CSV",
    "ReportType": "COLLECTED_FEES",
    "DateRangeBy": "ExecutionDate",
    "AfterDate": 1740787200,
    "BeforeDate": 1743544740,
    "Filters": {
        "Currency": "EUR"
    }
}