Create a report run

Start generating a report of all transactions that match the filter and options specified in the request body.

Use the returned report_run_id and the Retrieve report run details operation to check the status of the generation.

After generation is done, use the Download report file operation to retrieve the CSV. The file_url in the completed report run object is the request URL for that endpoint and requires the same authorisation as any other Merchant API request.

Report types​

The table below helps to choose the right report type for your use case:

Report type	What it covers
custom_report	Settled and processing transactions with configurable columns
settlement_report	All settled transactions, with a configurable set of columns
payments_report	All payments including failed and declined ones
payout_statement_report	All transactions contributing to a specific payout
icpp_fee_breakdown_report	IC++ fees per transaction for a specific IC++ charge

IDs across report types​

Each report type uses a different primary ID, depending on which system the data comes from:

ID column	System	Report types
payment_id, id	Acquiring system - identifies a payment attempt	payments_report, icpp_fee_breakdown_report
transaction_id	Core ledger - identifies the settlement entry created when a payment is captured	settlement_report, payout_statement_report, custom_report
order_id	Both systems - bridges the acquiring and ledger perspectives	settlement_report, payments_report, payout_statement_report, custom_report

Request​

Header parameters

Header parameters

Example: "Bearer sk_1234567890ABCdefGHIjklMNOpqrSTUvwxYZ_1234567890-Ab_cdeFGHijkLMNopq"

This parameter accepts the Merchant API Secret key to authorise requests coming from the merchant's backend.

It ensures that ensures that each request is authenticated and authorised by verifying the secret key. The secret key should be included in all request headers as a Bearer token.

Info

For more information, see: Authentication

Request body

Body any

A settlement report contains all the query information for generating reports of settled transactions associated with a Merchant account.

Filtering parameters to be applied to the report.

Note

For settlement_report and custom_report, from and to are evaluated against the transaction created_date, not the original payment-start timeframe or the payment_created_date and payment_captured_date columns.

This parameter specifies the start boundary for filtering report data. It accepts ETC/UTC date and time in ISO 8601 format and includes all matching records on or after this timestamp.

Combined with the to parameter, this determines the report's timeframe, including all matching records between the two values.

For example, by setting the from parameter to 2021-01-01T00:00:00Z, the report will include matching records from the first second of January 1, 2021, UTC, and onwards.

This parameter specifies the end boundary for filtering report data. It accepts ETC/UTC date and time in ISO 8601 format and includes all matching records before this timestamp (exclusive).

Combined with the from parameter, this determines the timeframe for the report, including all matching records between the two values.

For example, setting the to parameter to 2021-12-31T23:59:59Z will include all matching records in the report up to, but not including, the last second of December 31, 2021, UTC.

Possible values: [payment, refund, dispute]

Select source entity families to be included in the report.

Value	Description
payment	Include rows originating from payment settlement activity.
refund	Include rows originating from refund activity.
dispute	Include rows originating from dispute and chargeback activity.

Note

These values are filter input categories. They do not map 1:1 to the CSV type output column. For example, a settlement report filtered with payment, refund, and dispute can still return CSV type values such as SETTLEMENT, REFUND, CHARGEBACK, and CHARGEBACK_REVERSAL.

Possible values: [completed, processing, cancelled, reverted]

Select transactions by state to be included in the report.

Value	Description
completed	Include transactions that reached their final successful state.
processing	Include transactions that are still being processed.
cancelled	Include transactions that were cancelled before final completion.
reverted	Include transactions that were reversed after initial creation.

If not provided, only completed transactions will be included in the report.

Possible length: >= 3 characters and <= 3 characters
Example: "GBP"

Select transactions with specific currencies to include in the report. Provide ISO 4217 currency code in upper case.

Info

For more information about the supported currencies, see: Help Center.

Select transactions by location ID to be included in the report.

Info

For more information, see: Locations.

Possible values: [csv]
Example: "csv"

Format of the generated report file.

Possible values: [settlement_report, custom_report, payments_report, payout_statement_report, icpp_fee_breakdown_report]
Example: "settlement_report"

Type of the report.

Report type	Description
settlement_report	All settled transactions associated with a Merchant account, with a configurable set of columns.
custom_report	Settled and processing transactions associated with a Merchant account, with a configurable set of columns.
payments_report	Payments report provides details of all payments associated with a Merchant account, including failed and declined payments. Supports filtering by from and to creation timestamps, and optionally by entity_states.
payout_statement_report	Payout statement Reports provide a detailed breakdown of all transactions contributing to a specific payout amount. It requires the additional parameter filter.payout_id, which should be obtained from the payout ID retrieved via the payout list endpoint or from webhook events.
icpp_fee_breakdown_report	IC++ fee breakdown reports provide a detailed breakdown of fees for each IC++ transaction related to a payout. It requires the additional parameter filter.icpp_charge_id, which should be obtained from the related_icpp_charge_id column in the Payout statement report. A separate report should be generated for each IC++ transaction.

Further options to customise the report.

Example: "Europe/London"

Defaults to ETC/UTC. Defines the output timezone for all timestamps displayed in the report.

Has no effect on from or to parameters.

Possible values: [transaction_id, order_id, original_order_id, started_date, updated_date, completed_date, payment_created_date, payment_captured_date, type, state, description, merchant_order_ext_ref, customer_id, amount, currency, settlement_amount, settlement_currency, payment_method, fee_amount, fee_currency, processing_fee_amount, processing_fee_currency, browser_url, location_id]
Example:

[
  "transaction_id",
  "type",
  "amount",
  "currency",
  "settlement_amount",
  "settlement_currency"
]

Names of the columns to be included in the report.

If the columns parameter is not defined in the request, all available columns will be included in the report. An empty array will return an error.

Available columns:

Column name	Description
transaction_id	Unique identifier of the ledger transaction related to an order.
order_id	Unique identifier of the order.
original_order_id	Unique identifier of the original order. For refunds and chargebacks, references the order being reversed.
started_date	Start timestamp shown on the row. For payment rows, this is the payment start timestamp. For non-payment rows such as refunds and chargebacks, this is the transaction start timestamp. Separate from the report filter timeframe.
updated_date	Last update timestamp shown on the row. For payment rows, this is the payment update timestamp. For non-payment rows such as refunds and chargebacks, this is the transaction update timestamp. Separate from the report filter timeframe.
completed_date	Completion timestamp shown on the row. For payment rows, this is the payment completion timestamp. For non-payment rows such as refunds and chargebacks, this is the transaction completion timestamp. Separate from the report filter timeframe.
payment_created_date	Payment authorisation or creation timestamp for rows linked to a payment. Empty for refunds and non-payment-related rows where no payment timestamp applies. This is returned data, not the report filter key.
payment_captured_date	Payment capture timestamp for rows linked to a captured payment. Empty for refunds, non-payment-related rows, or payments not captured. This is returned data, not the report filter key.
type	Settlement report row type. A partial-settlement is represented by separate SETTLEMENT and REFUND rows, not a dedicated type.
state	State of the transaction.
description	Description of the order.
merchant_order_ext_ref	Merchant's order reference. The value of the merchant_order_data.reference field set when the order was created.
customer_id	Unique identifier of the customer.
amount	Total amount of the order.
currency	The ISO 4217 currency code of the order.
settlement_amount	Total amount settled on the merchant's account.
settlement_currency	The ISO 4217 currency code of the settled amount.
payment_method	Type of the payment method the customer used to pay for the order.
fee_amount	Total fee amount applied to the order, aggregated across all fee components (acquiring markup + interchange + scheme fees).
fee_currency	The ISO 4217 currency code of the total fee.
processing_fee_amount	Acquiring markup fee only — a subset of fee_amount. Represents Revolut's service fee, excluding interchange and scheme fees.
processing_fee_currency	The ISO 4217 currency code of the acquiring markup fee.
browser_url	The URL where the customer initiated the payment.
location_id	Unique identifier of the location related to the transaction.

Response​

Report run created, report started generating

Response body

Body object

Unique ID used for accessing report details. Use this to check report generation status.

Possible values: [processing, completed, failed, expired]

Current status of the report run.

Value	Description
processing	Report generation is still in progress.
completed	Report generation finished successfully and the file is available to download for 24 hours via file_url.
failed	Report generation failed and no report file is available.
expired	Report generation previously completed, but the 24-hour file availability window has elapsed and the file can no longer be downloaded.

Use this link to download the report file. Available only when status is completed, and only for 24 hours after report generation finishes.